~4Dgifts/toolbox/utilities/Parasol README
parasol Analyze FORTRAN source to assist in parallel porting.
Synopsis:
parasol [-s <topRtn>] [-rub] [-L [<lib>]] [-d <n>] <dir-list>
Usage: split [-s <funcname>] [-rubl] [-L [<lib>] [-d <n>] <dir-list>
-s <funcname> Name of function to start walking from.
<dir-list> List of directories to search.
-r Do recursively through subdirectories.
-u Print info on unreferenced functions.
-b Break separate functions into separate files.
-L [<lib>] Library to look in for unreferenced functions (to
remove from output tree). If no library given,
removes default list (libftn.so, libm.so).
-l List all function calls, even those that are in
standard libraries.
-d <n> Debug level (0-9).
Description:
Given that a developer wants to parallelize their application,
one of the problems that comes up is how common blocks and
variables should be maintained across the processes. For
example, in a database search situation, the parallelization
might be done by breaking the searches up across processors,
each processor running the same hierarchy of routines but on
different parts of the database or with different data. Each
of these processes will access common blocks that they could
change the contents of.
Usually, it must be determined if the included common blocks
are to be shared among the processes or should be private.
Also, it could be that only specific variables within the
common block should be shared/private while the rest of the
common block should be private/shared.
Also, there is the concept of static variables (in FORTRAN
these are 'SAVE' variables) which may or may not be actually
shared among processes.
Figuring out which common blocks/variables are to be shared
and private can become quite tedious.
This program "assists" in the determination process.
How to use:
Generate listing files of sources
---------------------------------
Since the FORTRAN compiler can generate a very informative
symbol table at the end of its listing, it was decided to take
advantage of this information, rather than write a FORTRAN
parser ourselves. So, this program takes as input the listing
files generated by the FORTRAN compiler. Just add the
following switches to all the source files that are to be used
as input to this program:
-listing -expand_include
This can be done in the developer's Makefile or build script
and then the developer can just recompile everything of
interest. It is important the the files be compiled with the
original switches also, so that FORTRAN will generate the
symbol tables as they would appear in the original executable.
Run parasol
---------
Run parasol on all the listing files generated providing it with
the name of the routine that will be the "main" or top-most
routine for each process. Split will read all files with the
.L extension in the directories specified.
Be sure to read the description for all the switches available
when running parasol.
It is recommended that the output from parasol be redirected to
a file. Sometimes the output can be quite lengthy and will
scroll off the top of the screen.
Analyze output
--------------
At this point, the developer needs to analyze the tables
generated to determine if common blocks need to be broken up
in some way and which common blocks can be shared and which
should be private. Also, if there are static variables, it
may be that these variables need to go in a common block that
is private to the processes or a common block that is shared.
The tables generated are described below (after the switches).
Switches:
-s <funcname> This switch identifies the "main" or top-most
routine for each of the individual processes.
Even though it is not required, a number of
tables depend on this and provide much better
information.
Assuming the application is going to be
modified by selecting a particular function
or subroutine (plus any functions/subroutines
it calls) and running it multiple times on
each of some number of processors, this
routine is used by parasol to determine all the
routines that will be referenced and what
variables and common blocks are used and may
cause an issue when run in parallel.
-r Search for .L files recursively through the
subdirectories.
-u Print tables on functions and common blocks
that are defined but not referenced by the
routines that will be parallelized.
-b While scanning, break each listing file up so
that each function or subroutine defined is in
its own file. At one time this was useful but
has limited use now. If the FORTRAN source
files define multiple functions or
subroutines, this option will break the
listing file up.
-L [<lib>] In order to remove as much clutter from the
output as possible, this program searches
specific FORTRAN libraries for routines and
does not print these in the tables generated.
For example, it isn't always useful to know
the routines that call ABS, MOD, INT, and
other standard FORTRAN library functions.
By default, parasol gets the routines defined in
/usr/lib/libftn.so and /usr/lib/libm.so.
If additional libraries are to be searched,
these can be added using the -L switch any
number of times providing the "full path" to
the library.
If the -L switch is given without giving a
library to search or with the place holder
'-', parasol will delete its list of libraries
to search, thus disabling this feature.
BEWARE: Split *assumes* the argument following
the -L switch is a library. If this is the
last switch provided to parasol before the
directory list, the first directory will be
read as a library to search. For this reason,
it is possible to provide the library name
'-', which is used to identify no-library.
-l This switch essentially disables the -L switch
and is equivalent to '-L -'. It causes all
routines called to be listed, whether in a
library or not.
-d <n> Debug output. A level number *must* be
provided. By default, debug is set to 1. A
setting of 9 (the max) will generate a lot of
information that is of little use to the user,
but might be of interest to someone modifying
the program. Also, higher debug values will
cause the format of the tables to get screwed
up and may make the output hard to read.
<dir-list> List of directories to search for .L files.
Output description:
Given that parasol is run with the -s option, the following
tables are generated:
CALL TREE
This provides information about the routines
that will be called. The first line, with an
indent of 0, should be the routine provided
with the -s switch. Each routine called will
be indented by two spaces for each depth
level.
UNCALLED FUNCTIONS
Generated only with the -u switch. This table
displays each routine that was defined but
never referenced. It also indicates what
routines are called by each routine and the
routines that call them.
MODIFIED COMMON BLOCKS
All common blocks that are modified or have
variables that are passed as parameters to
other routines are listed. Note that this
table displays all common blocks if the -s
option is not provided.
What is displayed is the common block name,
the function that modifies it or passes one of
its variables as an argument to another
routine, and the variable names that are
modified.
Note that a different line is generated for
each routine that modifies the common block.
Also, all the variables that are modified are
listed on one line (could be a *very* long
line). This is to assist in using 'grep(1)'
to search for items of interest and having
grep print all the necessary information.
MODIFIED COMMON BLOCKS (by functions not called)
Similar to MODIFIED COMMON BLOCKS except this
provides a list of those common blocks that
are modified by the routines that are defined
but not called in the tree generated. Note
that this table only prints out if the -u
option is provided.
STATIC (SAVE) VARIABLES
This table lists all the static variables (in
FORTRAN, 'SAVE' variables) found. The table
is provided as a list of routines followed by
a list of all the static variables declared
therein.
EQUIVALENCED VARIABLES
Identical to the STATIC VARIABLES table except
generated for EQUIVALENCE variables.
Documentation
Reference
OR, ...